This section describes BBEdit's powerful Clippings command. Clippings provide you an easy way to store and enter any sort of frequently used text, including program code, HTML markup, or just about anything else. Clippings can be language-sensitive, and their optional ability to run scripts and insert the results, further extends their flexibility and usefulness.
The Clippings menu contains commands which you can use to insert and manage text clippings. The Clippings menu also presents the contents of all available clipping sets. You can choose any available clipping to insert its contents into the active document, or use the Insert Clipping command. (See Inserting Clippings.)
Choosing the Clippings command from the Palettes submenu of the Window menu opens the Clippings palette, shown below. This window lists the contents of all available clipping sets. Clipping item names that are too long to fit within the width of the window are truncated with ellipses (...)
"Hovering" the mouse over such a truncated name displays a tool tip showing the full name. If you hold down the Option key, the tool tip will appear instantly, with no hovering delay. Names that fit entirely within the window without truncation do not display a tool tip.
Although BBEdit does not install any clipping sets by default, you can find a variety of customer-contributed clipping sets on our website, or create your own.
To install a new clipping set, just copy its folder into the "Clippings" folder within your local BBEdit application support folder.
In BBEdit 11 and later, there is no longer a single "active clipping set"; instead, all available clippings are now available at all times, unless a particular clipping set's name maps to an installed language. In that case, the clippings from that set are available only when the effective language in the active document matches the clipping's language. (For example, clippings from a clipping set "JavaScript.js" will by default only be available within JavaScript documents or content areas.)
You can override this default behavior by manually enabling clipping sets for any desired set of languages via the Clippings pane of the Setup window. Select one or more clipping sets, and click "Edit Enabled Languages" (or double-click the selected items) to edit the languages for which the set(s) are to be enabled. Within the "Edit Enabled Languages" panel, you can select multiple languages and turn them on or off at once.
The "Universal Items" clipping set no longer enjoys special behavior; instead, like all other clipping sets, it is automatically enabled for all languages by default, while any clippings that you place loose in the top level of the Clippings folder will automatically be available at all times.
These clipping selection and activation rules are intended to provide maximum flexibility while automatically doing the right thing as often as possible.
By default, the Set popup menu displays clipping sets and clipping items in alphabetical order. However, you can force them to appear in any desired order by including any two characters followed by a right parenthesis at the beginning of their name: for example "00)Web template" would sort before "01)HTML Template". The first three characters of such names are not displayed in the menu. You can also insert a divider by including an empty folder whose name ends with the string "-***". (You can use anything you want for the rest of the name, to make it appear where you want it in the menu.)
You can create a clipping by typing or pasting any desired text, or text and substitution placeholders, into a BBEdit document window and then choosing Save As Clipping from the Clippings menu. BBEdit will display a sheet in which you can name your clipping, and assign it to any existing or new clipping set.
You can also create a clipping from the current selection by choosing Save Selection as Clipping from the Clippings menu, and using the clipping creation sheet as described above. Using this command does not affect the name or location of the document from which you create the clipping.
If you wish to further organize clippings within a set, choose Open Clippings Folder from the Clippings menu. You can create multiple levels of subfolders inside the Clippings folder, to better organize different types of content. The first level of such subfolders appear in the Set popup menu of the Clippings palette, allowing you to reveal only the group of clippings you wish to work with at a given time. (Any clippings not placed in a subfolder are always shown in the Clippings palette.)
You can edit a clipping by holding down the Option key and choosing the desired item from the Clippings menu. You can also edit a clipping by selecting it in the Clippings palette, then holding down the Option key so that the Insert button changes to Edit, and clicking Edit, or by Option-double-clicking the clipping directly.
The quickest way to insert clippings is to use BBEdit's text completion feature. Just type a clipping item's name (or the beginning of a name), then either pause or invoke the Complete command by pressing F5 (or choosing it in the Edit menu) and BBEdit will display any matching clippings, as well as other available completions, in the completion popup.
You can select a clipping in the popup by using the up- and down-arrow keys and type Return or Tab to insert that clipping, replacing the word or partial word.
You can also select and insert a clipping by choosing the Insert Clipping command from the Clippings menu. You can either select a clipping by navigating the list with the up and down arrow keys, or type in a complete or partial string to filter the list of available clippings.
If there is a single match, BBEdit replaces the word with the contents of the matched clipping.
If there are multiple matches, BBEdit brings up the Insert Clipping popup (below) and lists all the matching clippings.
You can continue typing to further narrow the list and select a clipping, or use the up- and down-arrow keys to select a clipping and type Return to insert that clipping. You can also insert any listed clipping by double-clicking its name in the panel.
If there is no match, BBEdit brings up the Insert Clipping panel with focus in the filter field, but does not filter the clipping list.
You can type in the filter field to narrow the list and select a clipping, or use the up- and down-arrow keys to select a clipping, and then type Return to insert the selected clipping. You can also insert any listed clipping by double-clicking it. BBEdit replaces the word with the contents of the clipping and closes the panel.
You can also use wildcards with the Insert Clippings palette's search box. (The palette's interpretation of the pattern is strict; "ab*" will only match clippings whose names begin with "ab", whereas a non-wildcard "ab" will match any clipping whose name contains "ab".
Typing Shift-Return and Option-Return in the Insert Clippings palette's search field will behave as the same modifiers do when choosing an item from the Clippings menu: Shift-Return will reveal the clipping file in the Finder, while Option-Return will open it for editing.
Note: If there is a word or partial word before the insertion point, BBEdit looks for a clipping of the form 'clipping name begins with partial word'. However, when there is no word or partial word, BBEdit filters items in the Insert Clipping panel based on whether their names contain the currently-entered string. This makes it easier to filter clipping sets which contain many items having common prefixes.
You can use the Clippings menu to insert any listed clipping at the insertion point, or in place of the current selection, by choosing its name in the menu.
You can use the Clippings palette to insert any listed clipping by double-clicking its name in the window. Alternatively, you can click a clipping's name to select it and then click the Insert button, or drag the clipping directly to the desired location in a document window.
When you insert a clipping, BBEdit always reads the clipping file from disk—if a clipping's file is open and has unsaved changes, those changes will not be used.
The Set Key button in the Clippings palette lets you assign key equivalents for easy access to frequently used clippings.
To assign a key to a clipping:
You can use any combination of the Command, Shift, Option, and Control keys in the key equivalent, provided that it must use at least the Command or Control key to be valid. You can also use function keys, with or without additional modifiers.
Note: If you try to assign a key equivalent that is already used elsewhere, BBEdit warns you that there is a conflict and asks you whether you want to reassign that key equivalent to the new item.
To remove a key equivalent from a clipping:
When you insert a clipping containing a placeholder into an editing window, BBEdit replaces the placeholder with appropriate substitution text. This is similar to the operation of BBEdit's HTML Templates and Update features. The following table shows the placeholders you can use in a clipping:
|
Placeholder |
Replaced by... |
|---|---|
|
#BASENAME# |
The name of the file stripped of its rightmost period-delimited portion. For example, if the file is named "test.html", the base name is "test", while if the file is named "test.foo.html", the base name is "test.foo". |
|
#BLOCK# |
Inclusion of this placeholder guarantees that the inserted text will begin and end with a line break. |
|
#CLIPBOARD# |
Contents of the current clipboard |
|
#DATE# |
Current date, formatted according to your Format settings in the International panel of the System Preferences |
|
#DATETIME XXX# |
Inserts a localized, region-aware date whose format is specified by the ICU format string XXX (see "Date Formats" below) |
|
#DATETIME_GMT XXX# |
Inserts the universal, region-aware date whose format is specified by the ICU format string XXX (see "Date Formats" below) |
|
#FILE# |
File name of the document into which the item is inserted |
|
#FILE_EXTENSION# |
The filename extension for the file (determined as the rightmost period-delimited portion of the filename, without the period). For example, whether the file is named "test.html" or "test.foo.html", the filename extension is "html". |
|
#FUNCTION# |
If the item is being inserted into a source file, the name of the current function |
|
#GMTIME YYY# |
The current GMT time formatted according to the parameters YYY (see "Time Formats" below) |
|
#INDENT# |
When used in a clipping with multiple lines, causes every line after the first to be indented to the same whitespace level as the line in which the item was inserted (see the supplied WML clippings for examples) |
|
#INLINE# |
Strips all trailing vertical white space from the item before insertion |
|
#INSERTION# |
Marks the place where BBEdit will place the insertion point after inserting the item; if multiple #INSERTION# placeholders are used, the second and subsequent occurrences are replaced with a placeholder "<##>", which can be used with Go to Next/Previous Placeholder in the Search menu |
|
#LOCALTIME YYY# |
The current local time formatted according to the parameters YYY (see "Time Formats" below) |
|
#NAME# |
The long name of the active user account. (There is no intrinsic placeholder for the short name, but you can use #inline##system whoami# to obtain it.) |
|
#PLACEHOLDERSTART#label#PLACEHOLDEREND# |
Inserts a placeholder "hop" point which you can go to by using Next/Previous Placeholder. |
|
#SCRIPT filename# |
Result of running the specified AppleScript |
|
#SELECT# |
Selected text |
|
#SELECTIONORINSERTION# |
If there was a selection when the clipping was expanded, it will be put at this position; otherwise, the insertion point will remain here. |
|
#SELECTIONORPLACEHOLDER label# |
If there is an active selection, the placeholder will be replaced with the selected text.
If there is no selection, a placeholder named with the specified text ("label") will be inserted into the document.
This placeholder is particularly useful when building clippings for insertion via both BBEdit's auto-completion mechanism and the clippings palette (or direct key equivalent). |
|
#SELSTART# and #SELEND# |
Mark a range within the inserted material to be selected after the insertion. You can use multiple pairs of these placeholders within a single clipping. |
|
#SYSTEM shell_script# |
Given the full path to a shell command or script, BBEdit will run that command or script and insert the result. |
|
#TIME# |
Current time, formatted according to your Format settings in the International panel of the System Preferences |
|
#UUID# |
A 128-bit UUID (universally unique identifier), formed by combining a value unique to the computer on which it was generated (usually the Ethernet hardware address) with a value representing the number of 100-nanosecond intervals since October 15, 1582 |
Placeholders are not case-sensitive. If you want to include a literal placeholder in a clipping, escape the first # with a backslash, as in \#DATE#.
You can use multiple #SELSTART#/#SELEND# pairs together with any number of #INSERTION# placeholders.
Example:
Suppose you have defined the following clipping which contains an insertion placeholder:
typedef struct #SELECT#
{
#INSERTION#
} #SELECT#, *#SELECT#Ptr, **#SELECT#Handle;
If the selected text in your editing window is "MyStruct" and you insert this clipping, BBEdit will insert the following in the editing window:
typedef struct MyStruct
{
|
} MyStruct, * MyStruct Ptr, ** MyStruct Handle;
(where the vertical bar marks the position of the insertion point ).
Example:
Suppose you have defined the following clipping which contains multiple pairs of selection placeholders:
MyFancyFunction(#selstart#arg1#selend#, #selstart#arg2#selend#, #selstart#arg3#selend#);
When you insert this clipping, BBEdit will place the following text in the editing window:
MyFancyFunction(arg1, <#arg2#>, <#arg3#>);
and the string "arg1" will be selected. You can then use the Go To Next/Previous Placeholder commands from the Search menu to hop to the other arguments and enter the desired values.
When you apply a clippings item that contains multiple #INSERTION# cookies, the second and subsequent cookies are replaced with special jump placeholder strings. These strings have the form "<#...#>" where the content "..." between the two # signs is either alphanumeric text, or empty.
You can also directly create and insert jump placeholders at any desired points within a document.
Older versions of BBEdit generated temporary placeholders of the form "#*#" for clippings containing multiple instances of #INSERTION#. If you have any existing clippings which directly employ the old placeholder format, you will need to modify them to use the supported placeholder format.
In addition to jump placeholders, you can also insert "optional" placeholders of the form <#?#>. When the "Go to Next Placeholder" command would select such a placeholder, BBEdit will place the insertion point at the specified position and remove the optional placeholder.
Older versions of BBEdit generated temporary placeholders of the form "#·#" for clippings containing multiple instances of #INSERTION#. However, since the bullet character cannot be represented in all encodings, BBEdit now generates a different form of temporary placeholders.
Do not rely on the format of these temporary placeholders; use the supported placeholders (#INSERTION#, #SELSTART#, #SELEND#) instead. If you have any existing clippings which directly employ the old temporary placeholder format, you will need to modify them to use the supported placeholders.
The #DATETIME XXX# and #DATETIME XXX# placeholders allow you to insert the corresponding date and time values with flexible formatting.
In order to use these placeholders, you must substitute XXX with an ICU date/time format string. ICU is the mechanism used by Mac OS X for date formatting. For full details, please refer to the section "Date/Time Format Syntax" in the ICU documentation.
Examples:
#DATETIME EEE, MMM d, yy 'at' h:mm a#
produces:
Tue, Jul 3, 14 at 5:48 PM
#DATETIME_GMT EEE, MMM d, yy 'at' h:mm a#
produces:
Tue, Jul 3, 14 at 9:49 PM
#DATETIME EEEE 'at' h 'o''clock' a#
produces:
Tuesday at 5 o'clock PM
The #GMTIME YYY# and #LOCALTIME YYY# placeholders offer you the option to insert the specified time value with flexible formatting.
In order to use these placeholders, you must substitute YYY with a time format using the same expansion options offered by the `strftime' routine (see `man strftime' for further details).
Examples:
#LOCALTIME %r %z on %A# produces: 06:50:13 PM -0400 on Monday
#GMTIME %r %z# produces: 10:50:13 PM +0000
The #script filename# placeholder is a powerful option which allows you to insert variable or conditional content from a clipping, by invoking any compiled AppleScript or Unix shell script.
The script itself can either be located in the same folder as the clipping that invokes it (in which case you need only specify its name, such as "MyDateScript") or you can supply a full pathname to a script on any mounted volume (such as "Hard Drive:My Project:Scripts:MyDateScript"). An instance of a placeholder referencing the latter would be
#script Hard Drive:My Project:Scripts:MyDateScript#
The script must return a text string (or a value that can be coerced to a string). This result string can itself contain additional clippings placeholders, which will be interpreted before the item is inserted in the current document.
Note that this makes it possible for one script to invoke another. You must take care to not create a script execution loop, which could hang the application!